package edu.nf.llmtest.service;

import java.util.List;

/**
 * 天气服务接口
 * 
 * <p>提供天气查询相关功能，支持通过城市名称查询天气信息。</p>
 * 
 * @author bin
 * @since 2025/11/3
 */
public interface WeatherService {
    
    /**
     * 根据城市名称查询天气信息
     * 
     * <p>通过聚合数据API查询指定城市的天气情况，包括实时天气、温度、湿度、风向、风力、空气质量等信息。</p>
     * 
     * @param cityName 城市名称，例如："北京"、"上海"、"广州" 等
     * @param extensions 扩展参数，可选值：
     *                   <ul>
     *                     <li>"base" - 返回实况天气数据（当前实现统一返回实况数据）</li>
     *                     <li>"all" - 返回预报天气数据（当前实现统一返回实况数据）</li>
     *                   </ul>
     *                   如果为空或null，默认使用 "all"
     * @return 天气信息列表，包含以下格式的信息：
     *         <ul>
     *           <li>城市：{城市名称}</li>
     *           <li>天气：{天气状况}</li>
     *           <li>温度：{温度}℃</li>
     *           <li>湿度：{湿度}</li>
     *           <li>风向：{风向}</li>
     *           <li>风力：{风力}</li>
     *           <li>空气质量：{空气质量指数}</li>
     *         </ul>
     *         如果查询失败，返回空列表
     */
    List<String> getWeatherByCityName(String cityName, String extensions);
    
    /**
     * 根据城市名称查询天气情况（返回原始JSON响应）
     * 
     * <p>调用聚合数据API获取指定城市的天气信息，返回完整的JSON响应字符串。</p>
     * 
     * @param cityName 城市名称，例如："北京"、"上海"、"广州" 等
     * @return 天气API响应的JSON字符串，格式如下：
     *         <pre>
     *         {
     *           "error_code": 0,
     *           "reason": "success",
     *           "result": {
     *             "city": "北京",
     *             "realtime": {
     *               "info": "晴",
     *               "temperature": "25",
     *               "humidity": "60",
     *               "direct": "南风",
     *               "power": "3级",
     *               "aqi": "85"
     *             }
     *           }
     *         }
     *         </pre>
     *         如果查询失败或发生错误，返回 null
     */
    String queryWeather(String cityName);
}
